Restructure execution modes #2565
Conversation
|
Check out this pull request on See visual diffs & provide feedback on Jupyter Notebooks. Powered by ReviewNB |
|
One or more of the following people are relevant to this code:
|
Co-authored-by: abbycross <[email protected]>
docs/guides/execution-modes.mdx
Outdated
|
|
||
| **Interactive timeout (ITTL)** - This value cannot be configured. If no jobs are queued for the active session or batch within that window, the workload is temporarily deactivated. A job submitted to the session or batch reactivates the deactivated workload if the maximum timeout value has not been reached. | ||
|
|
||
| For full details about these values, including how to determine the ITTL value, review the [Maximum execution time guide.](/guides/max-execution-time) |
There was a problem hiding this comment.
I find it a bit confusing that when reading this guide on execution mode, there is a link to the max execution time page, which has a link back to this guide...
There was a problem hiding this comment.
which has a link back to this guide
I didn't find a link to this guide from the Max execution time one.
There was a problem hiding this comment.
It's the Specify the batch length. (and session length). They don't link back to this specific page but to the execution mode section.
There was a problem hiding this comment.
restructured some stuff.
|
Opened a PR to fix the broken readme links. |
| <Admonition type="note"> | ||
| The job must go through the normal queue to reactivate the workload. | ||
| </Admonition> | ||
| 3. If the maximum TTL value is reached, the workload ends and any remaining queued jobs fail. However, any jobs already running will run to completion. |
There was a problem hiding this comment.
any jobs already running will run to completion.
Isn't there something special about IBM Cloud jobs? That they won't run to completion if doing so would exceed the instance cap.
|
|
||
| A job's QPU time is listed in the **Usage** column on the IBM Quantum Platform [Workloads](https://quantum.ibm.com/workloads) page, or you can query it by running this command: `job.metrics()["usage"]["quantum_seconds"]` in `qiskit-ibm-runtime`. | ||
| The following video illustrates the session basic workflow, using sessions as an example: |
There was a problem hiding this comment.
| The following video illustrates the session basic workflow, using sessions as an example: | |
| The following video illustrates the basic workflow, using sessions as an example: |
It's weird to say "session basic flow" then "using session as an example"
| - **Session** | ||
| - All the benefits from batch mode. | ||
| - Dedicated and exclusive access to the QPU during the session active window. | ||
| - Useful for workloads that don’t have all inputs ready at the outset, for iterative workloads that require dedicated access, and for algorithms that require classical post-processing. |
There was a problem hiding this comment.
| - Useful for workloads that don’t have all inputs ready at the outset, for iterative workloads that require dedicated access, and for algorithms that require classical post-processing. | |
| - Useful for workloads that don’t have all inputs ready at the outset, for iterative workloads that require classical post-processing before the next one can run, and for experiments that need to run as tightly together as possible. |
for algorithms that require classical post-processing.
This is a bit ambiguous since technically most jobs require post processing (e.g. to distill hardware output to 1s and 0s).
| Generally, you can use batch mode unless you have workloads that don’t have all inputs ready at the outset. | ||
|
|
||
| - Use **batch** mode to submit multiple primitive jobs simultaneously to shorten processing time. | ||
| - Use **session** mode for iterative workloads, or if you need dedicated access to the QPU (quantum processing unit). |
There was a problem hiding this comment.
Nit - we use QPU all over the place without spelling out what it stands for, so why here 😛
|
|
||
| In this case, if you were using job or batch mode, each job generated by step (2) needs to go back through the queue. This drastically increases the experiment length (wall clock time) due to the queuing time. It could also take longer to converge due to device drift. That is, every iteration is supposed give you a better result, but device drift could make subsequent results worse. | ||
|
|
||
| In addition, if you use [PEA](/guides/error-mitigation-and-suppression-techniques#pea) or [PEC](/guides/error-mitigation-and-suppression-techniques#pec), you can [learn the noise model](/guides/noise-learning) once and apply it to subsequent jobs when running in dedicated session. This usually doesn't work with batch or job mode because the noise model could become stale by the time the next iteration runs. |
There was a problem hiding this comment.
| In addition, if you use [PEA](/guides/error-mitigation-and-suppression-techniques#pea) or [PEC](/guides/error-mitigation-and-suppression-techniques#pec), you can [learn the noise model](/guides/noise-learning) once and apply it to subsequent jobs when running in dedicated session. This usually doesn't work with batch or job mode because the noise model could become stale by the time the next iteration runs. | |
| In addition, if you use [PEA](/guides/error-mitigation-and-suppression-techniques#pea) or [PEC](/guides/error-mitigation-and-suppression-techniques#pec), you can [learn the noise model](/guides/noise-learning) once and apply it to subsequent jobs when running in dedicated session. This usually doesn't work with batch or job mode because the noise model could become stale by the time the next job is out of the queue. |
| @@ -113,7 +156,7 @@ session.close() | |||
| ``` | |||
|
|
|||
| <span id="cancel"></span> | |||
| ## Cancel a session | |||
| ### Cancel a session | |||
There was a problem hiding this comment.
We can cut this section out if you think the page is too long, since this is a more obscure function.
There was a problem hiding this comment.
In fact, I think we can also cut out Invoke multiple primitives in a session. The example used in Open a session already demonstrated this.
| <span id="sessions-versus-batch-usage" /> | ||
| # Choose the right execution mode | ||
|
|
||
| Utility-scale workloads can take many hours to complete, so it is important that both the classical and quantum resources are scheduled efficiently to streamline the execution. Execution modes provide flexibility in balancing the cost and time tradeoff to use resources optimally for your workloads. There are several aspects to consider when choosing which execution mode to use, such as _usage_, overall execution time (maximum time to live, or TTL), and time between jobs (interactive TTL). |
There was a problem hiding this comment.
This intro paragraph says "such as usage", but no where in the execution mode section talks about how usage is calculated for each mode.
| <span id="usage"></span> | ||
| ## Usage | ||
|
|
||
| Usage is an important consideration when choosing which execution mode to use. It is a measurement of the amount of time the QPU is locked for your workload. |
There was a problem hiding this comment.
This seems a bit out of place because (1) if they need to be on the same page, we should first explain what usage means before telling you how to get an estimation of that, and (2) this paragraph immediate jumps into choosing execution modes, even though we are in the Manage jobs section, not execution mode.
There was a problem hiding this comment.
Maybe this can be restructured as
title: Workload usage
- What is it and why you should care
- How usage is calculated for each execution mode.
- Usage for failed and canceled jobs
- How to find actual usage on IQP, using the provider and REST API
- How to find an estimation of usage right after submission
| The usage reported on the dashboard or by using the API is the time a QPU is locked for your workload. Failed or canceled jobs count toward your usage in certain circumstances - see the [Failed and canceled jobs](#failed-job) section for details. | ||
|
|
||
|
|
||
| To find the usage time for your batch or session, in `qiskit-ibm-runtime` 0.30 or later, run `batch.usage()` or `session.usage()`. When using an older version of `qiskit-ibm-runtime` (>= 0.23 and < 0.30), the usage can be still be found in `session.details()["usage_time"]` and `batch.details()["usage_time"]`. |
There was a problem hiding this comment.
Given <0.30 was more than 3 months ago, maybe we don't have to show how it works with the old version?
| <Admonition> | ||
| If you use Qiskit Runtime on IBM Cloud, the session or batch is immediately terminated when the cost limit is reached. | ||
| </Admonition> | ||
|
|
||
| <span id="max-job"></span> | ||
| ## Job maximum execution time | ||
|
|
There was a problem hiding this comment.
This section has
The QPU-determined job timeout value
What is our definition of QPU? Because the timeout is not determined by the quantum processor itself. It's determined by the Qiskit Runtime service.
closes #2133
preview: https://qiskit.github.io/documentation/pr-2565/guides/execution-modes